package jmine.tec.services.api.export;

import java.util.List;

import jmine.tec.services.io.ServiceBean;

/**
 * Interface a ser implementada para exportadores de uma certa entidade. É capaz de criar serviços de inclusão da entidade, além de extrair
 * objetos que devem ser exportados antes de depois da entidade presente. Tipicamente, entidades exportadas após são associações com
 * entidades fortes ou realmente entidades fracas.<br/>
 * Claro, não é necessário colocar todas as associações no extractAssociations. Na prática, este método é apenas para auxiliar na construção
 * dos serviços, renderizando os elementos associados após a exportação da entidade específica do exporter.<br/>
 * Ex.:<br/>
 * No módulo Kernel do jTec, MPhase é uma entidade fraca, pois existe sempre ligada a um MProcess. Portanto um suposto exporter de MProcess
 * retorna suas MPhases como entidades fracas. O Exporter de MPhase, por seu lado, retornaria um objeto que representasse sua associação com
 * suas dependências para que um exporter próprio, capaz de gerar um serviço que adicione uma MPhase como dependente de outra. No exemplo,
 * existem 3 serviços distintos: inclusão de MProcess, inclusão de MPhase e inclusão de dependências de MPhase com outra MPhase.<br/>
 * Entidades exportadas antes podem ser, por exemplo, uma dependencia.<br/>
 * Vale a pena chamar a atenção de que uma entidade a ser exportada não é necessariamente uma entidade persistível. Ela pode ser qualquer
 * objeto que represente alguma coisa. Ex.: Um objeto pode representar uma associação, ou representar uma validação, ou um processamento.<br/>
 * <br/>
 * <br/>
 * O comportamento acima se refere à action de INCLUIR. Para auxiliar na exportação também existem 2 outras actions: BUSCAR - utilizara
 * quando é necessária uma referência para executar uma inclusão ou validação, utilizada tipicamente quando diversos parâmetros são
 * necessários para identificar uma entidade, e um serviço específico é utilizado para encontrá-la e salvar uma referência.<br/>
 * VALIDAR - especifica que deve ser criada uma validação daquela entidade, deve ser criado um serviço que irá verificar se a entidade
 * criada na importação possui o mesmo estado da entidade original.
 * 
 * @author lundberg
 * @param <E> tipo da entidade exportada por este Exporter
 */
public interface EntityExporter<E> {

    /**
     * Gera uma lista de ServiceBeans que descrevem serviços para a inclusão da entidade dada. Não é necessário gerar serviços para inclusão
     * das entidades fracas, pois isso deve ser gerenciado pelo ExportActor responsável, que saberá que entidades são essas através do
     * método extractAssociations.
     * 
     * @param referenceMap mapa de referencias. Caso o serviço gere uma referencia, esta deve ser adicionada no mapa.
     * @param entity entity
     * @return List de ServiceBean
     */
    List<ServiceBean> export(ReferenceMap referenceMap, E entity);

    /**
     * Retorna a lista de objetos que devem ser exportados antes da exportação da entidade dada. Pode ser utilizado, por exemplo, para a
     * importação de dependências. Todos os objetos retornados devem ter um exporter correspondente.
     * 
     * @param entity entity
     * @return List de objetos a serem exportados antes.
     */
    List<Object> exportBefore(E entity);

    /**
     * Retorna a lista de objetos a serem exportados após a entidade dada. Em geral são associações à entidades fortes e entidades fracas.
     * Todos os objetos retornados devem ter um exporter correspondente.
     * 
     * @param entity entity
     * @return List de objetos a serem exportados depois
     */
    List<Object> exportAfter(E entity);

    /**
     * Retorna a chave do exporter.
     * 
     * @return ExporterKey
     */
    ExporterKey getExporterKey();
}
